home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 98 / Skunkware 98.iso / src / net / bind-contrib.tar.gz / bind-contrib.tar / contrib / doc / doc.txt < prev    next >
Text File  |  1996-10-25  |  8KB  |  173 lines
  1. NAME
  2.      doc - diagnose unhealthy DNS domains
  3.  
  4. SYNOPSIS
  5.      doc [-p] [-e][-w][-v][-d] domain_name [parent_domain_name]
  6.  
  7. DESCRIPTION
  8.      Doc is an automated tool for verifying (to an extent) that a
  9.      domain is configured and functioning correctly.  It makes no
  10.      attempt to validate the  data  inside  a  domain,  only  the
  11.      structure.   The only required parameter is the valid domain
  12.      name of an existing domain.  Example:
  13.  
  14.                doc isi.edu.
  15.  
  16.      Previous versions of  doc  required  that  you  specify  the
  17.      parent (delegating) domain if it was not precisely one level
  18.      up from the domain being  checked  (or  specify  the  parent
  19.      nameservers  in  an appropriately named file).  Although the
  20.      option still exists to do that (and it may be required  with
  21.      some  complex  configurations),  some  heuristics  have been
  22.      added that make some attempt to handle parent  domains  that
  23.      are  more  than one level up from the current domain.  Exam-
  24.      ples:
  25.  
  26.           doc isi.edu. edu.             (correct, but not required)
  27.           doc isi.edu.                  (this works too)
  28.           doc 9.128.in-addr.arpa. arpa. (correct, but not required)
  29.           doc 9.128.in-addr.arpa.       (this works too)
  30.  
  31.      If you have problems, giving the parent information informa-
  32.      tion explicitly may help.
  33.  
  34.  
  35. OPTIONS
  36.      -p   Skip  testing  the  information  held   at   delegating
  37.           domain's servers.
  38.  
  39.           The default operation of doc includes testing that  all
  40.           of the servers for the delegating (parent) domain agree
  41.           about the delegation information held for the domain in
  42.           question.   Since  inconsistencies  discovered  at this
  43.           level may or may not indicate serious problems, one can
  44.           choose to skip the parent testing.  If so, doc uses the
  45.           first non-authoritative  list  of  NS  records  from  a
  46.           parent   domain  server  as  those  to  direct  further
  47.           queries.  If all of the parent domain servers are addi-
  48.           tionally  authoritative for the domain, the answer from
  49.           the last one queried is used.  This  may  be  a  useful
  50.           timesaver  if  you are regularly checking up on a large
  51.           number of domains.  [See also section FILES USED for  a
  52.           similar functionality.]
  53.  
  54.      -[e][w][v][d]  Specify the level of verbosity to standard output.
  55.  
  56.           The default mode of operation is to only print to stan-
  57.           dard output a summary of what is discovered.  In  addi-
  58.           tion, errors made in the process of testing (i.e. query
  59.           errors, errors causing doc to abort, etc) are noted.
  60.  
  61.               -e    Output comments about errors discovered.
  62.               -w    Output comments about warnings issued.
  63.               -v    Verbose output. Include misc. comments and output
  64.                     confirming correct behavior.
  65.               -d    Debug output. Checkpoint current (last)
  66.                     nameserver query.
  67.  
  68.           These output options are cumulative (i.e. -v implies -v
  69.           -w -e).
  70.  
  71.           NOTE: Parsing is very simple.  All  option  flags  must
  72.           come before the domain names.
  73.  
  74. FILES CREATED
  75.      In addition to the standard output, doc produces a log  file
  76.      named  log.<domain_name>,  which  it  places  in the current
  77.      directory.  This file includes all "verbose" level comments,
  78.      followed  by  the  nameserver responses to the queries (in a
  79.      slightly masticated form).
  80.  
  81.      While running, doc creates several temporary  files  in  the
  82.      current directory.  These files have names of the form:
  83.  
  84.           <domain_name>.*
  85.  
  86. FILES USED
  87.      Doc expects the auxiliary  files:  doc1.awk,  doc3.awk,  and
  88.      doc4.awk  to  reside in the current working directory.  This
  89.      can be overridden by changing the program to look  for  them
  90.      in  a  directory  indicated in a shell variable intended for
  91.      this purpose.  If your System Administrator  installed  doc,
  92.      they'll need to make the necessary modification.
  93.  
  94.      Doc looks for the  file  DNsrv.<parent_domain_name>  in  the
  95.      working  directory.  If it exists, doc does not make a stan-
  96.      dard query to discover  the  list  of  nameservers  for  the
  97.      parent  domain.   Rather it queries the list of servers con-
  98.      tained in this file to obtain delegation information for the
  99.      domain  being  tested.   This may be useful if one regularly
  100.      tests a series of domains,  all  with  the  same  delegating
  101.      zone,  where  one  of the servers in known to be foul.  This
  102.      server would simply be omitted from the the DNsrv.* file.
  103.  
  104.      awk, sed & dig (version 2.0 or higher) are  expected  to  be
  105.      found in your normal path.  If not, you may want to alias to
  106.      the full path inside of doc itself.
  107.  
  108. DETAILS
  109.      See file INFO (included with distribution tar)  for  details
  110.      of procedure.
  111.  
  112.  
  113. BUGS
  114.      The exit code returned via the shell is only 8  bits.   This
  115.      could cause a problem in the value returned by the auxiliary
  116.      file doc3.awk.  This hasn't been seen yet (a "poison  confi-
  117.      guration" is not likely to occur yet), and hopefully will be
  118.      corrected if/when doc is re-implemented (see below).
  119.  
  120.      The current implementation  is  fairly  simple  (albeit  not
  121.      pretty),  so it is not expected to abort unexpectedly.  How-
  122.      ever, this version (2.0) is an initial attempt at automating
  123.      this  task.   Further development is expected in identifying
  124.      the appropriate queries, analysis,  and  subsequent  conclu-
  125.      sions  that are made.  Hopefully once the design of the test
  126.      suite has become more stable, a less "patchwork"  production
  127.      version of doc will be done.
  128.  
  129. COMMENTS
  130.      The previous authors effectively stopped further development
  131.      and  support  in 1990.  Starting with version 2.1, the offi-
  132.      cial anonymous FTP site for doc is ftp.vix.com  as  part  of
  133.      the  the latest distribution of BIND (see the BIND Home Page
  134.      at <URL:http://www.isc.org/isc/>).  It will likely  also  be
  135.      made    available    in    the    DNS   Resource   Directory
  136.      <URL:http://www.is.co.za/andras/computer/dnsrd/> in the near
  137.      future.
  138.  
  139.      Relatively minor modifications have been made  with  version
  140.      2.1,  mostly  to  make the program a bit more robust in han-
  141.      dling parent (delegating) domains for  the  use  of  Defense
  142.      Information Systems Agency personnel.
  143.  
  144.      This program is being shared with the rest of  the  Internet
  145.      on  a  unsupported  basis.   If you have any enhancements or
  146.      changes you have made, please let us know.  We'd love to see
  147.      them,  with an eye towards integrating them into our version
  148.      (and also into the publicly  available  version).   However,
  149.      keep  in  mind  that I'm not getting paid (nor do I have the
  150.      time) to support the whole Internet on this tool.
  151.  
  152.      With the previous authors no longer  providing  support  for
  153.      doc,  it  becomes  far  less likely that a "less 'patchwork'
  154.      production version" will ever become available.
  155.  
  156. INFO
  157.      The name doc comes from Domain Obscenity  Control,  in  that
  158.      the  kinds of problems it looks for are considered "obscene"
  159.      from the perspective of a well-managed DNS.
  160.  
  161. TO DO
  162.      RFC 1537 SOA value conformance checking (warnings only).
  163.  
  164. PREVIOUS AUTHORS
  165.      Steve Hotz (hotz@isi.edu) Paul Mockapetris (pvm@isi.edu)
  166.  
  167. MODIFICATIONS BY
  168.      Brad Knowles (brad@birch.ims.disa.mil)
  169.  
  170. SEE ALSO
  171.      dig(1),  bind operators guide (BOG),  RFCs:  1034,1035,1535-
  172.      1537,1713,xxxx
  173.